Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / pcl10.arc / PCL.DOC < prev next >

Wrap

Text File | 1991-07-20 | 44.3 KB | 2,315 lines

Pascal Communications Library ( PCL ) for Turbo Pascal 4.0 through 6.0 USER REFERENCE MANUAL Version 1.0 20 May 1991 Copyright (C) 1991 By MarshallSoft All rights reserved MarshallSoft PO Box 4543 Hunstville, AL 35815 (205) 881-4630 Page 1 Table of Contents Chapter Page Introduction.................................3 Registration.................................4 Serial COM Ports.............................5 RS232........................................6 National INS8250 UART........................7 Revision History.............................7 Warranty.....................................7 Using the Library............................8 Compiling.................................9 Problems.................................10 Library Reference...........................11 SioBaud..................................12 SioBrkKey................................13 SioBrkSig................................14 SioCrtWrite..............................15 SioDTR...................................16 SioDelay.................................17 SioDone..................................18 SioError.................................19 SioGetc..................................20 SioKeyPress..............................21 SioKeyRead...............................22 SioLine..................................23 SioModem.................................24 SioParms.................................25 SioPutc..................................26 SioRTS...................................27 SioReset.................................28 SioRxBuf.................................29 SioRxFlush...............................30 SioRxQue.................................31 SioTimer.................................32 SioUnGetc................................33 Function Summary............................34 Error Code Summary..........................35 Page 2 Introduction The Pascal Communications Library ( PCL ) is an asynchronous communications library designed for experienced software developers programming in Turbo Pascal ( version 4.0 and up). An IBM PC/XT/AT or compatible is required. The PCL features: o 16 communications functions + 6 support functions. o Receiver is interrupt driven. o Runs from 300 baud to 115,200 baud. o Supports COM1, COM2, COM3, and COM4. o Adjustable receive queues from 8 bytes to 16 KB. o Control-BREAK error exit. o 11 comm error conditions trapped. o Allows 2 ports to run concurrently. o Complete modem control & status. o Written in hand optimized assembly language. o Low overhead & very reliable ! A typical application program using PCL might look like the following code outline: +----------------------------------------------------------------+ | program YourProgram | | uses PCL; | | ... | | ... | | var Buffer : array[0..1023] of Char; | | ... | | begin (* YourProgram *) | | RetCode := SioRxBuf(Port,Buffer,Size1024); | | RetCode := SioParms(Port,NoParity,OneStopBit,WordLength8); | | RetCode := SioReset(Port,Baud2400); | | ... | | ... ( application code ) | | ... | | RetCode := SioDone(Port); | | end. (* YourProgram *) | +----------------------------------------------------------------+ A simple terminal emulator program CALLPGM.C is provided in source code form as an example of the use of PCL functions. CALLPGM can be used to call up bulletin board services or mainframe computers. If you find any problems with the Pascal Communications Library or have any suggestions for improvement, please call or write. A C language version of PCL ( called CCL ) is available. Custom versions of PCL can be developed for special needs. Custom communication packages can also be developed. Call for prices. Page 3 Registration The shareware version of PCL.LIB is provided so that you may personally determine the usefulness of the product for yourself. If you can use PCL, please register your use with us. MarshallSoft PO Box 4543 Huntsville, AL 35815-4543 Please pay by check in US dollars. Payment must accompany purchase orders. Print the file PCL.INV if an invoice is needed. The registered package is $35 postpaid and includes: o PCL.PAS PCL Unit. o PCL_LIB.ASM PCL library source code. ( without the shareware screen ) o PCL.DOC PCL User Reference Manual. o Backbone bound printed User Reference Manual. o Telephone support for one year. o All future updates are $10 PCL_LIB.ASM is the source code for the library. The source code is copyrighted by MarshallSoft. The user is granted a license to use the PCL object code in his own application only. PCL_LIB.ASM is not shareware and may not be sold or given away to anyone. The registered user will receive the latest version of PCL by return mail. A 5.25" diskette is provided unless a 3.5" diskette is requested when ordering. Page 4 Serial COM Ports IBM PC compatible computers can have up to four serial ports. The BIOS table located at address 40:0000 has room for four communication port addresses: COM1 to COM4. During boot up, the COM1 and COM2 addresses are placed in the BIOS table providing that the hardware is present. Unfortunately, the COM3 and COM4 addresses are not placed in the table in DOS through version 3.3. This can be corrected by using DEBUG to assemble the following program SETCOM3 which should be added to the AUTOEXEC.BAT file. When executed, this program will place the standard COM3 port address 03E8 in the BIOS table. For COM4, change 03E8 to 02E8 and [0004] to [0006]. PUSH DS MOV AX,0040 MOV DS,AX MOV AX,03E8 MOV [0004],AX POP DS MOV AX,4C00 INT 21 Please note that you must have the physical hardware present ! Page 5 RS-232C RS-232 is the name of the serial data interface standard used to connect computers to modems. Most IBM compatible computers are built with at least one serial port and use either DB9 ( 9 pin ) or DB25 ( 25 pin ) connectors. A summary of these pins and their function follows. For more detailed information, refer to one of the many books dealing with RS-232 interfacing. Signal Ground Pin 7 (DB25), Pin 5 (DB9) The SG line is used as the common signal ground, and must always be connected. Transmit Data Pin 2 (DB25), Pin 3 (DB9) The TX line is used to carry data from the computer to the modem. Receive Data Pin 3 (DB25), Pin 2 (DB9) The RX line is used to carry data from the modem to the computer. Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9) The DTR line is used by the computer to signal the modem that it is ready. Data Set Ready Pin 6 (DB25), Pin 6 (DB9) The DSR line is used by the modem to signal the computer that it is ready. Request to Send Pin 4 (DB25), Pin 7 (DB9) The RTS line is used to "turn the line around" in half duplex modems, but is not necessary in full duplex modems. Clear to Send Pin 5 (DB25), Pin 8 (DB9) The CTS line, like the RTS line, in not necessary in full duplex modems. Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9) The DCD line is used by the modem to signal the computer that a data carrier signal is present. Ring Indicator Pin 22 (DB25), Pin 9 (DB9) The RI line is asserted when a 'ring' occurs. Page 6 National INS8250 The Pascal Communications Library is based on the standard National INS8250 UART. The 8250 consists of 6 register ports based at the following standard addresses: COM1 = 3F8H COM2 = 2F8H COM3 = 3E8H COM4 = 2E8H If you are not familiar with the INS8250, several good books are available. Although a knowledge of the 8250 is not necessary to use PCL, a general knowledge of the theory of operation of Univeral Asynchronous Receiver / Transmitters ( UARTs ) is recommended. Offset R/W Register 0 R/W Receiver ( read ) / Transmitter ( write ) 1 R/W Interrupt Enable 2 R Interrupt Identification 3 R/W Data Format ( Line Control ) 4 R/W RS-232 ( Modem ) Control 5 R/W Line Status 6 R/W RS-232 ( Modem ) Status Revision History Version 1.0 -- 20 May 1991 -- original release. Warranty The user of this software assumes all liability for its use. In no case shall MarshallSoft be liable for any damages, including any incidental or consequential damages. Page 7 Using the Library The first thing to do is to copy all the files from the PCL distribution disk to a working disk, and put the original PCL distribution disk in a safe place. The PCL has been tested on a TANDY 1000 ( IBM PC clone ), a TANDY 3000 ( IBM AT clone ), a TANDY 1400LT ( IBM XT clone ), and a Gateway 2000 Cache ( 25 MHZ 80386-DX ). For an example of PCL use, examine the terminal emulator program CALLPGM.PAS. The user should compile CALLPGM.PAS as a test of the library. If you have two computers, then you can connect them together with a null modem cable and run CALLPGM on both machines. Whatever is typed on one machine should appear on the other, and vice versa. Depending on the design of the null modem cable, CALLPGM.PAS may need to be modified so that it does not wait for DSR. This is clearly documented in the CALLPGM.PAS code. If you have a modem, then use CALLPGM to call up any bulletin board system ( BBS ). There are many free BBSs around the country. Look in any issue of "Computer Shopper" ( available in bookstores, computer shops, and many grocery stores ) for a list of current systems. Page 8 Compiling Registered users may wish to assemble PCL_LIB.ASM. Use the /MX switch in order to disable automatic conversion from lower case to to upper case. To assemble using the Microsoft assembler: MASM PCL_LIB /MX; To build the library TPU: TPC PCL To compile the sample program: TPC CALLPGM Page 9 Problems If you cannot get your application to run properly, first compile and run the terminal emulator program CALLPGM provided on your distribution disk. If CALLPGM runs correctly, then you have made a programming mistake in your application. MarshallSoft cannot debug your application, especially over the telephone! However, consider each of the following when searching for an error in your application. 1. Did you include the "uses PCL" statement ? 2. Is your receive buffer large enough ? If you are using 1K data blocks in a file transfer protocol such as YMODEM, then your receive buffer should be 1K or more. 3. Have you selected too high a baud rate ? Always start with the slowest baud rate. If only one COM port is being run, you should be able to run at 38400 baud. 4. Are you attempting to run another application in the background ? Try running without any other programs running in the background. 5. If you are running two COM ports simultaneously, are you using seperate receive buffers ? ( you should ). 6. Did SioReset return a zero value ? If not, then you must call SioReset again. See CALLPGM.PAS for an example. If CALLPGM does not run, then either there is a physical connection problem or your computer isn't as compatible as you thought! Registered users can always call (205) 881 - 4630 after 5 PM CST Monday through Friday for help. Page 10 Library Reference The remainder of this manual list all the PCL functions. Every library function will return a value as follows: 1. Negative values for error conditions. See last page of this manual for a list of error values and their meanings. 2. Non-negative values when returning data ( eg: SioLine ). 3. Zero otherwise. When debugging an application, be sure to test all return values. Use SioError to print the associated text for errors. /*** example code segment ***/ RetCode := SioFunction(); (* any PCL function *) if RetCode < 0 then begin RetCode := SioError(RetCode); (* ...do some stuff... *) end; Page 11 SioBaud Function Sets the baud rate of the selected port. Syntax function SioBaud(Port,BaudCode : Integer) : Integer; Arguments Port : Port selected (COM1..COM4). BaudCode : Baud code. Remarks The SioBaud function sets the baud rate without resetting the port. It is used to change the baud rate after calling SioReset. Baud Code Baud Rate PCL Name 0 300 Baud300 1 600 Baud600 2 1200 Baud1200 3 2400 Baud2400 4 4800 Baud4800 5 9600 Baud9600 6 19200 Baud19200 7 38400 Baud38400 8 57600 Baud57600 9 115200 Baud115200 Returns -2 : Port not enabled. Must call SioReset first. -4 : Bad port selected. Value must be 0 to 3. -11 : Bad baud rate code. See above code values. Example /* do auto baud detect */ for Code = 0 to 9 do begin RetCode := SioBaud(Port,Code); RetCode := SioPutc(Port,'A'); if SioGetc(Port,18) = Ord('A') then writeln('Baud rate detected'); (*...do something here...*) end end; Page 12 SioBrkKey Function Return non-zero if the Control-BREAK key was pressed. Syntax function SioBrkKey : Integer; Remarks The SioBrkKey function returns a TRUE value ( non-zero ) if the Control-BREAK key was pressed, else it returns a zero. Use SioBrkKey as a safety exit from a polling loop. Don't mix this function up with SioBrkSig. Returns -1 : Control-BREAK was pressed. 0 : Control-BREAK was NOT pressed. Example while TRUE do begin if SioBrkKey then begin writeln('User typed Contrl-BREAK'); RetCode := SioDone(Port); halt; end; (* do some other stuff *) end; Page 13 SioBrkSig Function Asserts, cancels, or detects BREAK signal. Syntax function SioBrkSig(Port : Integer; Cmd : Char) : Boolean; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Cmd : ASSERT, CANCEL, or DETECT Remarks The SioBrkSig function controls the BREAK bit in the line status register. The legal commands are: ASSERT ('A') to assert BREAK CANCEL ('C') to cancel BREAK DETECT ('D') to detect BREAK ASSERT, CANCEL, and DETECT are defined in PCL.PAS. See CALLPGM.PAS for an example of the use of SioBrkSig. Returns -2 : Port not enabled. Must call SioReset first. -4 : Bad port selected. Value must be 0 to 3. -6 : Illegal command. Expected 'A', 'C', or 'D'. >0 : BREAK signal detected ( DETECT only ) Example (* Assert BREAK for 1 second *) RetCode := SioBrkSig(Port,ASSERT); RetCode := SioDelay(18); RetCode := SioBrkSig(Port,CANCEL); (* Detect BREAK *) if SioBrkSig(Port,DETECT) then begin writeln('BREAK signal detected'); (* ...do some more stuff... *) end Page 14 SioCrtWrite Function Write character to the screen. Syntax function SioCrtWrite(ch : Char) : Integer; Arguments ch = Character to write Remarks The SioCrtWrite function uses the BIOS to write a single character to the screen at the current cursor location. SioCrtWrite is faster than a call to the Pascal library and for this reason is included in PCL. Returns zero Example Ch := SioGetc(COM1,18); if Ch <> -1 then begin (* do some stuff *) end Page 15 SioDTR Function Set, clear, or read the Data Terminal Ready ( DTR ) bit. Syntax function SioDTR(Port,Cmd : Integer) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Cmd : DTR command ( SET, CLEAR, or READ ) Remarks The SioDTR function controls the Data Terminal Ready ( DTR ) bit in the modem control register. Commands ( defined in PCL.PAS ) are: SET ('S') to set DTR ( ON ) CLEAR ('C') to clear DTR ( OFF ) READ ('R') to read DTR Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. -5 : Not one of 'S', 'C', or 'R'. 0 : DTR is OFF (READ Command). >0 : DTR is ON (READ Command). Example (* turn DTR on for modem connected to COM4 *) RetCode := SioDTR(COM4,SET); Page 16 RetCode := SioDelay Function Delays one or more tics. Syntax function SioDelay(Tics : Integer) : Integer; Arguments Tics : Number of timer tics ( 18.2 per second ) Remarks The SioDelay function is used to delay one or more timer tics, where each timer tic is approximately 55 milliseconds ( 18 to the second ). See SioTimer also. Returns zero Example RetCode := SioDelay(5*18); (* delay 5 seconds *) Page 17 SioDone Function Terminates further serial processing. Syntax function SioDone(Port : Integer) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Remarks The SioDone function terminates further serial processing. SioDone MUST be called before exiting your application so that interrupts can be restored to their original state. Failure to do this can crash the operating system. If you forget to call SioDone before exiting, be sure to re-boot your computer. Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. Example (* terminate processing for COM3 *) RetCode := SioDone(COM3); Page 18 SioError Function Displays error in text. Syntax function SioError(Code : Integer) : Integer; Arguments Code : Error code returned from a PCL function Remarks The SioError function displays the error in text corresponding to the error code. During development of a communications application, it is a good idea to always test return codes, and print out their descriptions with SioError. Returns none Example RetCode := SioReset(Port,Baud4800); if RetCode < 0 then RetCode := SioError(RetCode); Page 19 SioGetc Function Reads the next character from the serial line. Syntax function SioGetc(Port,Tics : Integer) : Integer; Arguments Port : COM1 to COM4 Tics : Number of timer tics Remarks The SioGetc function reads the selected serial port. The function will wait for the number of system tics given by the 'Tics' argument before returning 'timed out'. There are 18 tics to the second. To specify no waiting, call SioGetc with Tics = 0. Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. -1 : If timed out. >0 : Character read. Example RetCode := SioGetc(COM1,1); if RetCode <> -1 then writeln('Character is ', chr(RetCode) ); else writeln('Timed out'); Page 20 SioKeyPress Function Detects if keyboard has been pressed. Syntax function SioKeyPress() : Boolean; Remarks The SioKeyPress function uses the BIOS to test the keyboard for a key press. Returns zero Example if SioKeyPress begin (* ...do something... *) end; Page 21 SioKeyRead Function Reads the keyboard. Syntax function SioKeyRead : Integer; Remarks The SioKeyRead function uses the BIOS to read the keyboard. Will wait until a character is typed. SioKeyRead is faster than using the Pascal library. Returns character typed. Example if SioKeyPress then begin RetCode := SioKeyRead(); end Page 22 SioLine Function Reads the line status register. Syntax function SioLine(Port : Integer) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Remarks The SioLine function reads the line status register. The individual bit masks are as follows: $20 = Transmitter Buffer Empty. $10 = Break detected. $08 = Framming error. $04 = Parity error. $02 = Overrun error. $01 = Data ready. The above are documented in the file PCL.PAS. Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. >0 : Line status ( rightmost byte of word ). Example RetCode := SioLine(Port); if(RetCode and (FramingError or ParityError or OverrunError)) <> 0 then begin if (RetCode and FramingError) <> 0 then writeln('Framing Error'); if (RetCode and ParityError) <> 0 then writeln('Parity Error'); if (RetCode and OverrunError) <> 0 then writeln('Overrun Error') end else writeln('No error'); Page 23 SioModem Function Reads the modem status register. Syntax function SioModem(Port : Integer; Mask : Char) ; Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Mask : Modem function mask Remarks The SioModem function reads the modem register. The bit definitions for the function mask are as follows: Bit PCL.PAS Name Function 7 DCD Data Carrier Detect 6 RI Ring Indicator 5 DSR Data Set Ready 4 CTS Clear To Send 3 DeltaDCD Delta DCD ( DCD has changed ) 2 DeltaRI Delta RI ( RI has changed ) 1 DeltaDSR Delta DSR ( DSR has changed ) 0 DeltaCTS Delta CTS ( CTS has changed ) Bits 4 through 7 represent the absolute state of their respective RS-232 inputs. Bits 0 through 3 repesent a change in the state of their respective RS-232 inputs since last read. The above definitions are also in the PCL.PAS file for use by your application program. Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. >0 : Modem status ( rightmost byte of word ). Example (* any change in DCD ? *) Status := SioModem(Port,DeltaDCD); if Status < 0 then begin RetCode := SioError(Status); Halt; end; else writeln('DCD status = ', SioModem(Port,DCD) ); Page 24 SioParms Function Sets parity, stop bits, and word length. Syntax function SioParms(Port,ParityCode,StopBitsCode,WordLengthCode: Integer) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) ParityCode : Parity code [0,1,2] StopBitsCode : Stop bits code [0,1] WordLengthCode : Word length code [0,1,2,3] Remarks The SioParms function sets the parity, stop bits, and word length. If the default parity ( none ), stop bits ( 1 ), or word length ( 8 ) is not acceptable, then they can be changed by calling SioParms. SioParms can be called either before or after calling SioReset. See file PCL.PAS. Value Description PCL.PAS Name ParityCode: *0 no parity NoParity 1 odd parity OddParity 2 even parity EvenParity StopBitsCode: *0 1 stop bit OneStopBit 1 2 stop bits TwoStopBits WordLengthCode: 0 5 data bits WordLength5 1 6 data bits WordLength6 2 7 data bits WordLength7 *3 8 data bits WordLength8 * = Default Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. -7 : Bad parity code selected. Value must be 0 to 2. -8 : Bad stop bits code. Value must be 0 or 1. -9 : Bad word length code. Value must be 0 to 3. Example RetCode := SioParms(COM1,NoParity,OneStopBit,WordLength8); Page 25 SioPutc Function Transmit a character over a serial line. Syntax function SioPutc(Port : Integer; Ch : Char) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Ch : Character to send Remarks The SioPutc function transmits one character over the selected serial line. Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. Example crc := 0; for i = 0 to 127 do begin crc := crcupdate( buffer[i], crc); RetCode := SioPutc(Port, buffer[i]); end; RetCode := SioPutc(crc); Page 26 SioRTS Function Sets, clears, or reads the Request to Send ( RTS ) line. Syntax function SioRTS(Port : Integer; Cmd : Char) : Integer; Arguments Port : COM1 to COM4 Cmd : RTS command ( SET, CLEAR, or READ ) Remarks The SioRTS function controls the Request to Send ( RTS ) bit in the modem control register. Commands ( defined in PCL.PAS ) are: SET ('S') set RTS ( ON ) CLEAR ('C') clear RTS ( OFF ) READ ('R') read RTS Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. -5 : Command is not one of 'S', 'C', or 'R'. 0 : RTS is OFF (READ Command). >0 : RTS is ON (READ Command). Example (* turn off RTS for modem *) RetCode := SioRTS(Port,CLEAR); Page 27 SioReset Function Initialize a serial port for processing. Syntax function SioReset(Port,BaudCode : Integer) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) BaudCode : baud code Remarks The SioReset function initializes the selected serial port. SioReset should be called after calling SioParm and SioRxBuf but before making any other calls to PCL. SioReset uses the parity, stop bits, and word length value previously set if SioParm was called, otherwise the default values ( see SioParm ) are used. Recall that COM1 and COM3 share the same interrupt vector and therefore cannot operate simultaneously. Similiarly, COM2 and COM4 cannot operate simultaneously. Any other combination of two ports can be used. See SioBaud for a list of the baud rate codes, or see "PCL.PAS". Returns -4 : Bad port selected. Value must be 0 to 3. -11 : Bad baud rate code selected. Value must be 0 to 9. Example RetCode := SioRxBuf(COM1,Buffer,Size128); RetCode := SioReset(Com1,Baud38400); if RetCode = 0 then writeln('RESET ok'); else begin RetCode := SioError(rc); if (RetCode and OverrunError) <> 0 then writeln('Overrun Error'); if (RetCode and ParityError) <> 0 then writeln('Parity Error'); if (RetCode and FramingError) <> 0 then writeln('Framing Error'); if (RetCode and BreakDetected) <> 0 then writeln('Break Detected'); end; Page 28 SioRxBuf Function Sets up receive buffers. Syntax function SioRxBuf(Port,BufferOfs,BufferSeg,SizeCode : Integer) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Buffer : Receive buffer SizeCode : Buffer size code Remarks The SioRxBuf function passes the address and size of the receive buffer to PCL. Recall that PCL requires a receive buffer for each port in simultaneous operation since the receive function is interrupt driven. SioRxBuf passes the receive buffer to PCL for both the primary ( COM1/COM3 ) and secondary ( COM2/COM4 ) ports. It must be called before any incoming characters can be received. SioRxBuf should be called before SioReset. Buffer size codes are listed in "PCL.PAS". Size Code Buffer Size PCL.PAS Name 0 8 bytes Size8 1 16 bytes Size16 2 32 bytes Size32 3 64 bytes Size64 4 128 bytes Size128 5 256 bytes Size256 6 512 bytes Size512 7 1024 bytes Size1024 8 2048 bytes Size2048 9 4096 bytes Size4096 10 8192 bytes Size8192 11 16384 bytes Size16384 Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. -10 : Bad buffer size code. Value must be between 0 and 11. Example RetCode := SioRxBuf( COM1, RxBuf, 128); Page 29 SioRxFlush Function To flush the receive buffer associated with the specified port. Syntax function SioRxFlush(Port: Integer) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Remarks The SioRxFlush function will delete any characters in the receive buffer for the specified port. After execution, the receive buffer will be empty. Call SioRxBuf after resetting a port in order to delete any spurious characters. Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. Example (* setup receive buffer and reset port *) RetCode := SioRxBuf(COM1,buffer,Size1024); RetCode := SioReset(COM1,Baud115200); (* flush any spurious character *) RetCode := SioRxFlush(COM1); (* ready for serial processing ! *) Page 30 SioRxQue Function Returns the number of characters in the receive queue. Syntax function SioRxQue(Port : Integer) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Remarks The SioRxQue function will return the number of characters in the receive queue. It can be used to implement XON/XOFF flow control. Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. Example RetCode := SioRxBuf(COM1,Buffer,Size128); (* implement XON / XOFF *) count := SioRxQue(COM1); if (last=XON) and (count>120) then begin RetCode := SioPutc(COM1,char(XOFF)); last := XOFF; end if (last=XOFF) and (count<8) then begin RetCode := SioPutc(COM1,char(XON)); last := XON; end Page 31 SioTimer Function Returns the number of system clock tics since midnight. Syntax function SioTimer : Integer; Remarks The SioTimer function will return the number of system clock tics since midnight, at 18.2065 tics per second. This function is usefull for timeing various functions. Also see SioDelay. Returns timer tics Example Time := SioTimer(); (* do some stuff *) writeln('Elasped time ', SioTimer - Time ); Page 32 SioUnGetc Function "Un-gets" the last character read with SioGetc. Syntax function SioUnGetc(Port : Integer; Ch : Char) : Integer; Arguments Port : Port selected (COM1,COM2,COM3,or COM4) Ch : Character to unget Remarks The SioUnGetc function returns ( pushes ) the character back into the serial input buffer. The character pushed will be the next character returned by SioGetc. Only one character can be pushed back. This function works just like the "ungetc" function in the C language. Returns -2 : Port not enabled. Must call RetCode := SioReset first. -4 : Bad port selected. Value must be 0 to 3. Example RetCode := SioUnGetc(Port,c); Page 33 Function Sumary +-------------+----------+----------+----------+----------+ | Function | Arg1 | Arg2 | Arg3 | Arg4 | +-------------+----------+----------+----------+----------+ | SioBaud | Port | BaudCode | | | +-------------+----------+----------+----------+----------+ | SioBrkKey | | | | | +-------------+----------+----------+----------+----------+ | SioBrkSig | Port | Cmd | | | +-------------+----------+----------+----------+----------+ | SioCrtWrite| Ch | | | | +-------------+----------+----------+----------+----------+ | SioDTR | Port | Cmd | | | +-------------+----------+----------+----------+----------+ | SioDelay | Tics | | | | +-------------+----------+----------+----------+----------+ | SioDone | Port | | | | +-------------+----------+----------+----------+----------+ | SioError | Code | | | | +-------------+----------+----------+----------+----------+ | SioGetc | Port | Tics | | | +-------------+----------+----------+----------+----------+ | SioKeyPress| | | | | +-------------+----------+----------+----------+----------+ | SioKeyRead | | | | | +-------------+----------+----------+----------+----------+ | SioLine | Port | | | | +-------------+----------+----------+----------+----------+ | SioModem | Port | Mask | | | +-------------+----------+----------+----------+----------+ | SioParms | Port | Parity | StopBits |WordLength| +-------------+----------+----------+----------+----------+ | SioPutc | Port | Ch | | | +-------------+----------+----------+----------+----------+ | SioRTS | Port | Cmd | | | +-------------+----------+----------+----------+----------+ | SioReset | Port | BaudCode | | | +-------------+----------+----------+----------+----------+ | SioRxBuf | Port | Buffer | SizeCode | | +-------------+----------+----------+----------+----------+ | SioRxFlush | Port | | | | +-------------+----------+----------+----------+----------+ | SioRxQue | Port | | | | +-------------+----------+----------+----------+----------+ | SioTimer | | | | | +-------------+----------+----------+----------+----------+ | SioUnGetc | Port | Ch | | | +-------------+----------+----------+----------+----------+ Page 34 Error Code Summary Code Description 0 No error. -1 Timeout waiting for input. Only returned by SioGetc. -2 Port not enabled. Must call SioReset first. -3 No buffer available. Must call SioRxBuf before calling SioReset. -4 Bad port specified. Must be 0 to 3. Recall that COM1 is port 0, COM2 is port 1, etc. -5 Expected 'S', 'C', or 'R' as second argument. -6 Expected 'A', 'C', or 'D' as second argument. -7 Bad parity code specified. Must be 0 to 7. -8 Bad stop bits code specified. Must be 0 or 1. -9 Bad wordlength code specified. Must be 0 to 3. -10 Bad buffer size code specified. Must be 0 to 11. -11 Bad baud rate code. Must be 0 to 9. Page 35